<!DOCTYPE HTML>
<html><head>

  
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Ruby Packaging Standard, 0.5-draft</title>
    <style>
body {
  font: 14px/16px Corbel, Lucida Grande, serif;
  background-color: #ffffff;
  color: #000000;
  margin: 2em;
  max-width: 50em;
}

small {
  font-size: 12px;
}

h1 {
  font: 28px/32px Corbel, Lucida Grande, serif;
}

h2 {
  font: bold 16px/32px Corbel, Lucida Grande, serif;
  margin: 20px 0 12px 0;
  padding: 0;
}

p {
  padding: 0;
  margin: 8px 0;
}

ol, ul {
  margin: 0;
  padding: 0;
}

pre, code {
  font: 95% Consolas, Monaco, monospace;
}

pre {
  margin-left: 40px;
}
    </style>
  </head><body>
<h1>Ruby Packaging Standard, 0.5-draft</h1>

<p>The aim of this document is two-fold.  First, to specify a common
structure of how a Ruby package distributed as source (that is, but
not limited to, development directories, version-controlled
repositories, .tar.gz, Gems, …) should conform to.</p>

<p>Second, to document common and proven ways to structure Ruby 
packages,
and to point out certain anti-patterns that sneaked into common use.
It is by intent not to innovate.</p>

<p>(See <a href="http://www.ietf.org/rfc/rfc2119.txt"><small>RFC</small>
 2119</a> for use of
<small>MUST</small>, <small>SHOULD</small>, <small>SHALL</small>.)</p>

<h2>General</h2>

<p>Project names <small>SHOULD</small> only contain underscores as 
separators in their names.</p>

<p>If a project is an enhancement, plugin, extension, etc. for some 
other
project it <small>SHOULD</small> contain a dash in the name between the 
original name
and the project’s name.</p>

<p>File names and directory structure <small>SHOULD</small> correspond 
like this:</p>

<pre><code>Library: foo-bar
Directory: lib/foo/bar
Namespace: Foo::Bar

Library: foo_bar
Directory: lib/foo_bar
Namespace: FooBar
</code></pre>

<h2>Library files</h2>

<p>Library code <small>MUST</small> reside in <code>lib/</code>.</p>

<p>Libraries <small>SHOULD</small> use a directory as namespace, e.g. <code>lib/foo.rb</code>
 and
<code>lib/foo/**</code>.  (And, see above, thus limit their code to a 
module <code>Foo</code>.)</p>

<p>Libraries <small>SHOULD</small> <small>NOT</small> require code of 
the project that are outside of <code>lib/</code>.</p>

<p>Libraries <small>MUST</small> <small>NOT</small> <code>require 
'rubygems'</code> or modify the <code>$LOAD_PATH</code>,
unless they are specifically made for doing that (e.g. package 
managers).</p>

<p>Ruby library files <small>MUST</small> end with <code>.rb.</code></p>

<p>Library files <small>SHOULD</small> be installed with mode 0644.</p>

<h2>Executables</h2>

<p>Executables <small>MUST</small> reside in <code>bin/</code>.</p>

<p>Ruby executables <small>SHOULD</small> have a shebang line using <code>env</code>:</p>

<pre><code>#!/usr/bin/env ruby
</code></pre>

<p>Executables <small>SHOULD</small> <small>NOT</small> require code of 
the project that are outside of <code>lib/</code>.</p>

<p>Executables <small>SHOULD</small> <small>NOT</small> <code>require 
'rubygems'</code> or modify the <code>$LOAD_PATH</code>.</p>

<p>Executable files <small>SHOULD</small> <small>NOT</small> end with <code>.rb</code>.</p>

<p>Executable files <small>SHOULD</small> be installed with mode 0755.</p>

<h2>Extensions</h2>

<p>Extensions are directories which contain a <code>extconf.rb</code>.</p>

<p>Extensions <small>SHOULD</small> reside in <code>ext/</code>.</p>

<p>Extensions <small>SHOULD</small> be buildable with <code>ruby 
extconf.rb; make</code>.</p>

<p>Files ending with <code>.so</code>, <code>.dylib</code>, <code>.bundle</code>,
 <code>.dll</code>, <code>.exe</code> are
considered compiled extensions to be installed.</p>

<p>Extensions <small>SHOULD</small> be installed into an 
architecture-specific directory.</p>

<h2>Data files</h2>

<p>Data files and resources of the project belong to <code>data/$projectname</code>.</p>

<p>Data files <small>SHOULD</small> be found at runtime using:</p>

<pre><code>require 'rbconfig'
require 'rbconfig/datadir'
path = Config.datadir('$projectname')
</code></pre>

<p><small>XXX</small> find a way to make this work from checkouts, and 
with several
package management mechanisms being used.</p>

<h2>Tests</h2>

<p>Tests <small>SHOULD</small> reside in <code>test/</code> or <code>spec/</code>.</p>

<h2>History</h2>

<ul>
<li>09apr2010: First initial draft.</li>
<li>10apr2010: Fix binary permissions.</li>
<li>10apr2010: Add data files.</li>
<li>11apr2010: Formatting, more detail on Extensions and Data files.</li>
</ul>

  </body></html>